Inside Macintosh: QuickTime
QuickTime includes extensions to the Standard File Package that allow you to create and display file previews--information that gives the user an idea of a file's contents without opening the file. Typically, a file's preview is a small PICT image (called a thumbnail ), but previews may also contain other types of information that is appropriate to the type of file being considered. For example, a text file's preview might tell the user when the file was created and what it discusses. You can use the Image Compression Manager to create thumbnail images--see the chapter "Image Compression Manager" later in this book for more information about thumbnail images.
QuickTime provides new standard file functions that your application can use to display a file's preview during the Open dialog box. These functions allow your application to support previews automatically.
Before using these new standard file functions, make sure that the Image Compression Manager is installed. See the chapter "Image Compression Manager" in this book for information about the Image Compression Manager's Gestalt selector.
In addition, the Movie Toolbox includes two functions that allow you to create a preview for a file.
The Movie Toolbox provides two new standard file functions that allow you to display file previews in an Open dialog box in System 6 using standard file reply structures: SFGetFilePreview and SFPGetFilePreview . The SFGetFilePreview function (described on SFGetFilePreview ) corresponds to the existing SFGetFile function; the SFPGetFilePreview function (described on SFPGetFilePreview ) corresponds to the existing SFPGetFile function. Both of these new functions take the same parameters as their existing counterparts. For information about SFGetFile and SFPGetFile , see Inside Macintosh: Files .
All the functions for previewing files are present in System 6 except the CustomGetFilePreview function. The StandardGetFilePreview function is preferable and will work on System 6.
The SFGetFilePreview function uses the dialog box shown in Figure 33 . The SFPGetFilePreview function can also use this dialog box, if you do not supply your own.
Figure 33 SFGetFilePreview or SFPGetFilePreview dialog box without preview
You use these new functions in place of the existing standard file functions to indicate whether or not you want to allow the user to display previews during the Open dialog box. The user displays a file's preview by selecting a file in the dialog box and clicking Show Preview. When the user does so, the functions display the preview for the file, as shown in Figure 34 .
Figure 34 SFGetFilePreview or SFPGetFilePreview dialog box with preview
The preview area of the dialog box is displayed whenever previewing is enabled.
If your application requires it, you can customize the user interface for identifying files. The SFGetFilePreview function does not allow you to use a custom dialog box by creating your own dialog template resource. However, the SFPGetFilePreview function does let you access a custom dialog box of any resource type with the dlgID parameter.
Figure 35 shows the standard dialog box used by SFPGetFilePreview and SFGetFilePreview . Your dialog box and dialog filter function must support at least these dialog items.
Alter the dialog boxes only if necessary. Apple does not guarantee future compatibility if you use a customized dialog box.
Figure 35 Standard preview dialog box for SFGetFilePreview and SFPGetFilePreview
Items to the left of item 13 are visible only when previewing. If you want to define items that are visible only during a file preview, place them to the left of item 13 in your custom dialog box.
If your application defines a custom dialog box, be sure to include the following items in your dialog box definition:
enum
{
/* dialog items to include in dialog box definition for use
with SFPGetFilePreview function
*/
sfpItemPreviewAreaUser = 11, /* user preview area */
sfpItemPreviewStaticText = 12, /* static text preview */
sfpItemPreviewDividerUser = 13, /* user divider preview */
sfpItemCreatePreviewButton = 14, /* create preview button */
sfpItemShowPreviewButton = 15 /* show preview button */
};
The Movie Toolbox provides two new standard file functions, standardGetFilePreview and CustomGetFilePreview , that allow you to display file previews in an Open dialog box in System 7 using standard file reply structures (of type StandardFileReply ). The StandardGetFilePreview function (described on StandardGetFilePreview ) corresponds to the existing StandardGetFile function; the CustomGetFilePreview function (described on CustomGetFilePreview ) corresponds to the existing CustomGetFile function. Both of these new functions take the same parameters as their existing counterparts. See Inside Macintosh: Files for information about StandardGetFile and CustomGetFile .
The StandardGetFilePreview function uses the dialog box shown in Figure 36 . The CustomGetFilePreview function can also use this dialog box, if you do not supply your own.
Figure 36 StandardGetFilePreview or CustomGetFilePreview dialog box without preview
You use these new functions in place of the existing standard file functions whenever you want to allow the user to display previews during the Open dialog box. The user causes a file's preview to be displayed by selecting a file in the dialog box and clicking Show Preview. When the user does so, the functions display the preview for the file, as shown in Figure 37 .
Figure 37 StandardGetFilePreview or CustomGetFilePreview dialog box with preview
The preview portion of the dialog box is displayed only when the dialog box is showing a file's preview.
The SFGetFilePreview , SFPGetFilePreview , StandardGetFilePreview , and CustomGetFilePreview functions allow the user to automatically convert files to movies if your application requests movies. If there is a file that can be converted into a movie file using a movie import component, then the file is shown in the Standard File dialog box in addition to any movies. When the user selects the file, the Open button changes to a Convert button. Figure 38 provides an example of this dialog box.
Figure 38 Dialog box showing automatic file-to-movie conversion option
Choosing Convert displays a dialog box that allows the user to choose where the converted file should be saved. Figure 39 shows this dialog box.
Figure 39 Dialog box for saving a movie converted from a file
When conversion is complete, the converted file is returned to the calling application as the movie that the user chose. If you want to disable automatic file conversion in your application, you must write a file filter function and pass it to the file preview display function you are using. Your file filter function must call the File Manager's FSpGetFileInfo function on each file that is passed to it to determine its actual file type. If the File System parameter block pointer passed to your file filter function indicates that the file type is 'MooV' , and the actual type returned by FSpGetFileInfo is not 'MooV' , then the file filter function will convert this file. If you do not wish a file to be displayed as a candidate for conversion, your file filter function should return a value of true when it is called for that file.
See "File Filter Functions," for comprehensive details on the interaction of application-defined file filter functions with the file preview display functions. For information on FSpGetFileInfo , see Inside Macintosh: Files .
If your application requires it, you can customize the user interface for identifying files. The CustomGetFilePreview function allows you to specify a custom dialog box of any resource type with the dlgID parameter.
Figure 40 shows the standard dialog box used by CustomGetFilePreview . Your dialog box and dialog filter function must support at least these dialog items.
Alter the dialog boxes only if necessary. Apple does not guarantee future compatibility if you use a customized dialog box.
Figure 40 Standard preview dialog box for CustomGetFilePreview
Items to the left of item 13 are visible only when previewing. If you want to define items that are visible only during a file preview, place them to the left of item 13 in your custom dialog box.
If your application defines a custom dialog box, be sure to include the following items in your dialog box definition:
enum
{
/* dialog items to include in dialog box definition */
sfpItemPreviewAreaUser = 11, /* user preview area */
sfpItemPreviewStaticText = 12, /* static text preview */
sfpItemPreviewDividerUser = 13, /* user divider preview */
sfpItemCreatePreviewButton = 14, /* create preview button */
sfpItemShowPreviewButton = 15 /* show preview button */
};